═══ 1. Title page ═══ HFS/2 A Hierarchical File System Driver for OS/2 Copyright (C) 1996 by Marcus Better Based on "MacFS", Copyright (C) 1996 by Peter A. Dinda, George C. Necula, and Morgan Price ═══ 2. Introduction ═══ HFS/2 is a file system driver for OS/2 which reads and writes Macintosh diskettes. With HFS/2, a Macintosh diskette can be used seamlessly with OS/2 just as if it were an ordinary DOS diskette. At least, that is how it is supposed to be once the rough edges get smoothed out. This program supports 1.4MB Macintosh diskettes formatted with the Hierarchical File System only. Old 800k diskettes or diskettes formatted with the "flat" file system cannot be used. In the future, it should be possible to make HFS/2 handle hard disks as well. Warning: This program is in an early, experimental state. It is almost certainly lacking some important features, and may still have many bugs and problems. You should always make backup copies of any diskettes that you use with this program. HFS/2 is based on MacFS, a free, portable implementation of the Macintosh Hierarchical File System by Peter A. Dinda, George C. Necula, and Morgan Price. The source code for MacFS is incorporated in HFS/2, slightly modified. I have found it helpful to look at the source code of Matthieu Willm's ext2-os2 driver, and have borrowed some ideas from him. The IFS part of HFS/2 follows an architecture for a split ring 0/ring 3 IFS described in articles by Andre Asselin in the Electronic OS/2 Developer's Magazine. The latest version of HFS/2 is available on the WWW at http://www.abc.se/~m9111/HFS. I hope you will find HFS/2 useful. You are welcome to send me any comments, suggestions, bug reports and contributions. Marcus Better Email: Marcus.Better@abc.se ═══ 3. Licence and Conditions of Use ═══ Licence for HFS/2 Licence for MacFS ═══ 3.1. Licence for HFS/2 ═══ Disclaimer This program is supplied as is. The author assumes no responsibility for damages which may result from the use of this program. HFS/2 may be used and freely distributed within the limits stated below. You may also modify HFS/2 and incorporate it in other programs within these limits. 1. HFS/2 may be freely used for non-commercial purposes only. 2. If you alter HFS/2 in any way and distribute the work, then that work must be similarly free, and the source code must be freely available to the public. This program incorporates MacFS, which is covered by a licence of its own. HFS/2 is Copyright (C) 1996 by Marcus Better. ═══ 3.2. Licence for MacFS ═══ WARNINGS -------- THIS SOURCE CODE IS NOT PUBLIC DOMAIN, FREEWARE, SHAREWARE, or "COPY-LEFTED." THIS SOURCE CODE MAY BE FREELY DISTRIBUTED UNDER THE LIMITS SPECIFIED BELOW. THIS SOURCE CODE HAS NO ACTUAL OR IMPLIED WARRANTY OR GUARANTEE OF ANY KIND FROM PETER A. DINDA, GEORGE C. NECULA, MORGAN PRICE, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER PARTY. THIS SOURCE CODE IS NOT SUPPORTED BY PETER A. DINDA, GEORGE C. NECULA, MORGAN PRICE, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER PARTY. To the best of our knowledge, this source code, "MacFS", is correct and suitable. However, no warranty or guarantee of any kind, either actual or implied, is provided for this software. Additionally, no support is provided for this software. It is used at your own risk. ============================================================================== LICENSE ------- This source code, "MacFS", is Copyright (c) 1996 by Peter A. Dinda, George C. Necula, and Morgan Price Current version is available via: http://www.cs.cmu.edu/afs/cs.cmu.edu/usr/pdinda/html/pdinda.html ftp://ftp.cs.cmu.edu/user/pdinda Permission is granted to distribute and freely use and extend "MacFS", or to incorporate the "MacFS" source code into other software within these limits: 0) "MacFS" and any derivatives of "MacFS" must retain this license, display the above copyright notice when run, and include this file. 1) "MacFS" and any derivatives of "MacFS" may only be freely used for non-commercial purposes. If you are interested in commercial use of "MacFS", contact Peter A. Dinda (pdinda@cs.cmu.edu). 2) "MacFS" and any derivatives of "MacFS" may not be used for military purposes. 3) Peter A. Dinda (pdinda@cs.cmu.edu) must be notified of any derivatives of "MacFS" In simple terms, "MacFS" may be freely used for any non-commercial, non-military purposes. Derivatives of "MacFS" must be similarly free and Peter A. Dinda (pdinda@cs) must be notified of their existence. Commercial use of "MacFS" and commercial derivatives of "MacFS" are NOT ALLOWED under this license. To use "MacFS" commercially, contact Peter A. Dinda (pdinda@cs.cmu.edu) for more information. Peter August Dinda pdinda@cs.cmu.edu Doctoral Student, School of Computer Science, Carnegie Mellon University http://www.cs.cmu.edu/afs/cs.cmu.edu/usr/pdinda/html/pdinda.html ═══ 4. Installation instructions ═══ The following steps describe how to install HFS/2. 1. Unpack the distribution archive hfsnnn.zip into a directory anywhere on your system. 2. Add the following line to the CONFIG.SYS file on your boot drive: IFS=d:\path\HFS.IFS where d:\path\ is the path to the directory where you unpacked the files. The line must be located after the IFS= statement for the file system where HFS/2 resides, if any. 3. You may add the line RUN=d:\path\HFS.EXE to the CONFIG.SYS file to have the Control Program HFS.EXE started in the background at boot time. This program must be activated, either in this way or simply by running it from an OS/2 prompt, before using HFS/2. 4. Optionally add the HFS/2 directory to the PATH line in CONFIG.SYS. ═══ 5. Using HFS/2 ═══ HFS/2 is made up mainly of two parts:  the IFS, and  the Control Program. The IFS resides in the file HFS.IFS, and is loaded at boot time with a line in CONFIG.SYS. The Control Program resides in the file HFS.EXE. In addition, the HFS/2 package contains the utilities PREPARE.EXE, SYNC.EXE and FSKILL.EXE. Their function is described in the following sections. Here is a short summary of the steps involved in using a Macintosh diskette with HFS/2: 1. Make sure the Control Program is running. 2. Insert the diskette into a diskette drive. We will assume this drive is A: for this example. 3. If the diskette has not been prepared for use with HFS/2, prepare it with the command PREPARE /P A: See the section on PREPARE for a closer description of this command. 4. Access the files on the diskette in any way you like. 5. Synchronize the data on the diskette by invoking SYNC A: See the section on SYNC for further information on this command. 6. Optionally restore the diskette with the command PREPARE /R A: 7. Remove the diskette from its drive. ═══ 5.1. The Control Program ═══ The file HFS.EXE is known as the Control Program. It is the Control Program that carries out most tasks on behalf of the file system driver. HFS.EXE can be started either from an OS/2 prompt, or using a RUN= statement in CONFIG.SYS. There are no command-line options for HFS.EXE. When the Control Program is started, it connects to the IFS and starts processing file system requests. Macintosh volumes can be accessed only when the Control Program is running. The Control Program will refuse to load if another instance of the program is already running. Warning: If the Control Program is interrupted while a Macintosh diskette is mounted, data may be lost and the diskette left in an inconsistent state. It is best to let the Control Program run once it has been started. If you need to interrupt it for some reason, be sure to sync and remove all diskettes first. The Control Program may also cause a fault as a result of a bug. If this happens, you should remove any Macintosh diskettes immediately. It may also be necessary to run the FSKILL utility before continuing if the Control Program traps. FSKILL will tell the HFS.IFS to disconnect from the crashed Control Program. ═══ 5.2. Preparing a diskette for use with HFS/2 ═══ Because of the way OS/2 handles diskettes, a Macintosh diskette cannot be used directly on an OS/2 system. The diskette needs an OS/2-compatible boot sector in order to be recognized. Naturally, Macintosh diskettes do not have OS/2-compatible boot sectors. PREPARE.EXE remedies this by supplying an OS/2-style boot sector. The syntax for this command is PREPARE /P d: where d: is the drive with the diskette to be prepared. PREPARE.EXE will save the original boot sector in a data file in the current directory. The name will be the hexadecimal serial number of the diskette. If a file with that name already exists, PREPARE will complain and not prepare the diskette. In order to restore the boot sector from this data file, use the command PREPARE /R d: This will copy the saved original boot sector from the data file back to the diskette. The data file must be found in the current directory, or PREPARE will complain. Macintosh diskettes usually do not need a boot sector unless they are used to boot from. An HFS diskette will work in a Macintosh computer even if it has an OS/2 boot sector. If you do not intend to restore a diskette, you can delete the data file generated by PREPARE. I believe there are better ways to work around this problem, and hope that future versions of HFS/2 will make the PREPARE program unnecessary. ═══ 5.3. Synchronizing a volume ═══ When an HFS diskette is accessed, the file system driver keeps some HFS data structures in memory for performance reasons. Before the diskette is removed from the drive, these structures must be written to the diskette. This is known as synchronizing the buffers, and it is done by running the program SYNC.EXE. Invoking SYNC is simple. Just type SYNC d: at a command prompt to sync the diskette in drive d:. If the sync succeeds, the program will notify you that the diskette may be removed. Warning: If you remove an HFS diskette from the drive without running SYNC first, the diskette may be left in an inconsistent state. You can, however, reinsert the diskette immediately after and continue using it without losing data. ═══ 6. Building the source ═══ The tools needed The sources The Ring 0 piece The Ring 3 piece ═══ 6.1. The tools needed ═══ To build HFS/2, you will need two C compilers: a 16-bit compiler for the IFS, and a 32-bit compiler for the Control Program and the utilities. Small modifications to the sources and makefiles may be necessary if you use different compilers than the ones listed below. Some modifications to the makefiles will be necessary either way in order to adjust them to your system. I used the following tools to develop HFS/2.  emx 0.9b (gcc) for the 32-bit parts.  Borland C 3.1, Turbo Assembler and Borland's MAKE utility for the IFS.  GNU Make version 3.67.  The library OS2286.LIB which came with IBM VisualAge C++ 3.0, for linking with the 16-bit part.  The IFS Toolkit, which is available from various IBM sources and includes the library FSHELPER.LIB.  Header files from the Warp Toolkit (which came with IBM VisualAge C++), used by the 16-bit part. ═══ 6.2. The sources ═══ The file hfssrc.zip contains the source tree. Some of the source files have long filenames, so you will have unzip it to an HPFS drive. The directories in the tree are as follows: . The root directory of the development tree contains header files shared by the ring 0 and ring 3 pieces, as well as the top-level Makefile which is only used to create the distribution archive. .\Ring0 This directory contains the source for the ring 0 piece (the IFS). .\Ring3 This directory contains the source for the Control Program and the utilities. .\Ring3\MacFS This is a slightly modified version of MacFS. .\doc The source for the documentation. ═══ 6.3. The Ring 0 piece ═══ The .\Ring0 directory in the development tree contains C and asm sources, and a makefile for Borland's MAKE utility. You will have to edit the makefile so that the paths are correct for your system. The makefile contains compiler options for BCC. I have sometimes experienced unexpected results after changing some of these options, in particular those related to optimizations. It seems that BCC can sometimes "optimize" perfectly good code so that it no longer works correctly. If the DEBUG symbol is defined, then the IFS will print some debugging information through a logging facility. The messages are printed out by the logging thread of the Control Program if it is also compiled with DEBUG defined. To compile the IFS with debugging enabled, a vsprintf function is needed. For reasons of licencing, there is no such function included in this distribution, so you must supply your own. ═══ 6.4. The Ring 3 piece ═══ The .\Ring3 directory has several subdirectories, each with its own Makefile (for GNU Make). They are all invoked as sub-makes by the top-level makefile (.\Ring3\Makefile). Dependencies can be generated by doing a make dep This generates a dependency file called .depend in each subdirectory. However, the makefiles require the .depend files to be present from the beginning, so you will have to create an empty .depend file in each directory manually before you can run make. There are better ways to write makefiles to avoid this, I just haven't got around to it yet. Note that GNU Make doesn't like dependencies that contain drive letters because of the colons. This can be a problem if the default search path for gcc is given by the C_INCLUDE_PATH environment variable and that variable contains drive letters. gcc will prepend the pathname from C_INCLUDE_PATH to the header file name when it generates dependencies, so you will have to remove the drive letter from C_INCLUDE_PATH. As a consequence, the emx header files will need to reside on the same drive as the HFS/2 source. The TOPDIR variable in .\Ring3\Makefile will need to be modified to suit your system. When that is done, just type make to compile everything. If the symbol DEBUG is defined, HFS.EXE will print some information on its actions. It will also create a logging thread which prints messages from the IFS. ═══ ═══ The Control Program, HFS.EXE, is the part of HFS/2 that runs in ring 3 (user privilege level). In order to access a Macintosh diskette, the Control Program must be running.